Skip to content

docs: add todography coverage map of the Kubernetes API - #11

Merged
mkmik merged 2 commits into
mainfrom
docs-coverage-map
Oct 20, 2026
Merged

docs: add todography coverage map of the Kubernetes API#11
mkmik merged 2 commits into
mainfrom
docs-coverage-map

Conversation

@mkmik

@mkmik mkmik commented Oct 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Adds docs/map/, a todography map of which Kubernetes kinds have a template in k8s.libsonnet and which don't yet. Each kind is one small Markdown file, so the map can be updated in the same commit as the template.

What's on the map

Row What Kinds
Built-in All kinds served by Kubernetes v1.37 (from api/discovery in the v1.37.0 source) 79
Official add-on APIs kubernetes / kubernetes-sigs projects shipped as CRDs: Gateway API, volume snapshots, Cluster API, Karpenter, Vertical Pod Autoscaler, Secrets Store CSI Driver, kro, Kueue, JobSet, LeaderWorkerSet 55
Third-party add-on APIs Projects the library already supports (cert-manager, Prometheus Operator, Istio, Strimzi, Sealed Secrets, Vault secret operator, OpenShift routes) plus widely used ones (Argo CD, External Secrets, Flux, KEDA, Kyverno, Velero, OpenTelemetry Operator, CloudNativePG, NVIDIA GPU Operator, Cilium) 148
Library Shared pieces the templates build on: clusterScoped, PodTemplateSpec, named arrays, adopt 4

Each add-on area lists every kind in that project's CRDs and says which release and CRD file it was checked against, so a version change upstream is easy to spot later.

How kinds are marked:

  • done: has a template.
  • goal (to do, with a milestone): worth adding.
  • aspiration (to do, no milestone): might be added some day.
  • dropped: created by controllers or API calls (Node, Event, cert-manager Order, Karpenter NodeClaim, ...), so a template would add little.

Suggested order

  • m1, common app kinds: HorizontalPodAutoscaler, standalone PersistentVolumeClaim, NetworkPolicy, HTTPRoute, Argo CD Application and AppProject, cert-manager Issuer, ExternalSecret and SecretStore, PrometheusRule.
  • m2, cluster-wide kinds: StorageClass, PersistentVolume, IngressClass, PriorityClass, webhook configurations, ValidatingAdmissionPolicy (+Binding), ClusterIssuer, ClusterSecretStore. Without a template, these pick up the namespace set on the shared ObjectMeta, which is wrong for cluster-wide objects.
  • m3, later: LimitRange, ResourceQuota, ResourceClaimTemplate, Istio v1 VirtualService and DestinationRule.

Numbers

done partial to do dropped
Built-in 18 1 29 31
Official add-ons 0 0 44 11
Third-party add-ons 8 2 113 25

Checking it

cargo install todography
todography lint --strict   # passes: 0 errors, 0 warnings, 286 components
todography next            # what to add next
todography open            # the interactive page

Already reflects #10 (Strimzi KafkaTopic v1, Istio EnvoyFilter v1alpha3).

🤖 Generated with Claude Code

mkmik and others added 2 commits October 20, 2026 09:56
@mkmik @claude
docs: add todography coverage map of the Kubernetes API
deb0291 
docs/map is a todography map with one file per kind, showing whether
k8s.libsonnet has a template for it.

- Built-in: all 79 kinds in Kubernetes v1.37 (from api/discovery in the
  v1.37.0 source). Kinds created only by controllers or API calls are
  marked dropped.
- Official add-on APIs (kubernetes and kubernetes-sigs projects shipped as
  CRDs): Gateway API, volume snapshots, Cluster API, Karpenter, Vertical Pod
  Autoscaler, Secrets Store CSI Driver, kro, Kueue, JobSet, LeaderWorkerSet.
- Third-party add-on APIs: the projects the library already supports, plus
  widely used ones: Argo CD, External Secrets, Flux, KEDA, Kyverno, Velero,
  OpenTelemetry Operator, CloudNativePG, NVIDIA GPU Operator, Cilium.
- Each add-on area lists the kinds in the project's CRDs, and its AREA.md
  names the release and CRD source they were checked against.
- lib/ holds the shared pieces the templates are built on.

Milestones give the order to add the missing templates.

`todography lint --strict` passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mkmik @claude
docs: draw add-on APIs above built-in Kubernetes in the map
6d9660b 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mkmik
mkmik merged commit 3e832c3 into main Oct 20, 2026
1 check passed
@mkmik
mkmik deleted the docs-coverage-map branch October 20, 2026 08:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mkmik